home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Compendium Deluxe 2
/
LSD and 17bit Compendium Deluxe - Volume II.iso
/
a
/
prog
/
misc
/
xes120.lha
/
XES
/
Docs
/
Paginate.man
< prev
next >
Wrap
Text File
|
1994-11-09
|
26KB
|
626 lines
Paginate V1.00 User Manual Paginate V1.00
NAME
Paginate - Can do both pagination and line numbering on
files.
SYNOPSIS
Paginate <infile >outfile -F/K -f0/K -f1/K -ff/K -H/K -h0/K
-h1/K -hf/K -N/K -t/K/N -b/K/N -l/K/N -r/K/N -p/K/N -T/S
-F Default Format String for Footers
-f0 Format String for Even Paged Footers
-f1 Format String for Odd Paged Footers
-ff Format String for Footer on First Page
-H Default Format String for Headers
-h0 Format String for Even Paged Headers
-h1 Format String for Odd Paged Headers
-hf Format String for Header on First Page
-N Printf Style Format String for Line Numbering
-t Top Line for Each Page
-b Bottom Line for Each Page
-l Left Margin for Headers and Footers
-r Relative Right Margin for Headers and Footers
-p Number of First Page
-T Title Page
COPYRIGHT
Paginate Copyright (C) 1993 Fergus Duniho
DESCRIPTION
This program can do both pagination and line numbering on
files.
PAGINATION
The pagination involves breaking a text file up into
pages of equal length, and optionally marking each page
with a header, a footer, or both. The headers and footers
may contain the page number in various formats, as well
as the time and date in various formats. They may also
include any other text you want to put in them.
You may choose different headers and footers for odd and
even pages, as well as for the first page. You may also
choose to have no header or footer on the first page, on
odd pages, or on even pages. And you may choose to have
the same footer or header on all pages.
You may also choose to make the first page a title page.
A title page has no headers and footers on it. Also,
"Paginate" does not begin page numbering with a title
page. And as far as the headers and footers for the first
Page 1 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
page are concerned, "Paginate" does not regard the title
page as the first page. It considers it as the page prior
to the first page.
LINE NUMBERING
The line numbering consists of printing a string with the
line number in it at the beginning of each line. You may
choose the format of the line number, and you may put
other text in the line number string. The default is to
do no line numbering.
DEFAULT
Paginate -F "@C- #d -" -H "" -N "" -l 9 -r 65 -t 4 -b 57 -p 1
USAGE
Paginate reads from standard input and writes to standard
output. So, to use it with files, you have to use redirection
operators. The simplest way to use "Paginate" is without any
arguments, and it may look like this:
> Paginate <infile >outfile
This will paginate a file such that you get one inch margins
on all sides when you print it, or at least such that I will
when I print it on a laser printer I have access to. It will
also center the page number at the bottom of each page. And
the page number will be in decimal form surrounded by a pair
of hyphens like so: "- 1 -".
You can change Paginate's behavior by specifying arguments.
You may include arguments on the command line in any order.
You must identify each argument with an identifier that
begins with a hyphen. You can see these listed under
SYNOPSIS.
FORMAT STRINGS
The arguments for headers, footers, and line numbering are
format strings. The format strings may consist of text and
conversion specifier. A conversion specifier is a bit of text
that gets replaced by other text, such as a page number or
line number. The format strings for headers and footers may
also include formatting codes.
CONVERSION SPECIFIERS FOR LINE NUMBERING
Paginate uses printf() for line numbering. Since Paginate
uses the line number as the only other argument in
printf() besides the format string, the format string for
line numbering may include only one conversion specifier.
This conversion specifier must be one which turns an
Page 2 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
integer into a string. Here are the allowable conversion
specifiers for line numbering:
%c - unsigned char
%d, %i - decimal integer
%o - octal integer
%u - unsigned decimal integer
%x, %X - unsigned hexadecimal integer
Some of these, such as %c, may be useless for page
numbering, but they're provided anyway, since printf()
provides them.
If you know how many lines your document has, your output
will look best if put a number between the '%' character
and the character that follows it. For example, "%3d"
will print all your line numbers in a space with a width
of 3. See a description of printf() in any book on C for
more details.
CONVERSION SPECIFIERS FOR HEADERS AND FOOTERS
Paginate does not use printf() for headers and footers.
Instead, it uses strftime() plus some other conversions
that I wrote myself. This is because I wanted roman
numeral page numbers, and printf() does not provide this
feature. For the headers and footers, Paginate accepts
conversion specifiers for the date, the time, and the
page number.
The conversion specifiers it uses for the date and time
are the same as those used by the C function strftime().
Depending upon what compiler was used to compile the
version of Paginate you have available, the conversion
specifiers for date and time may vary. As long as the
compiler adhered strictly to the ANSI standard, here are
the conversion specifiers you may expect to use for the
date and time:
%a - abbreviated weekday name
%A - full weekday name
%b - abbreviated month name
%B - full month name
%c - date and time
%d - day of the month
%H - hour of the 24-hour day
%I - hour of the 12-hour day
%j - day of the year, from 001
%m - day of the month, from 01
%p - AM/PM indicator
%S - seconds after the minute
Page 3 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
%U - Sunday week of the year, from 00
%w - day of the week, from 0 for Sunday
%W - Monday week of the year, from 00
%x - date
%X - time
%y - year of the century, from 00
%Y - year
%Z - time zone name, if any
According to the tests I have done on the strftime()
function in DICE, which I compiled the Amiga version
with, "%W" might mean something else, since it gives a
value of 1 for April 27. The others seem to work as
expected.
Paginate also understands the following conversion
specifiers for the page number:
#d - page number in decimal
#o - page number in octal
#x - page number in hexadecimal
#b - page number in binary
#r - page number in lowercase roman numerals
#R - page number in uppercase roman numerals
Because paginate uses the number sign (#) and percent
sign (%) for conversion specifiers, and because it uses
the at sign (@) for formatting codes (see below), it also
recognizes the following conversion specifiers:
%% - percent character %
## - number sign (pound sign, octothorp, etc.) #
@@ - at sign @
Unlike the conversion specifiers for line numbering, the
conversion specifiers for headers and footers do not have
all the features that printf() conversion specifiers
have.
FORMATTING CODES
Paginate uses formatting codes to position text in the
headers and footers. It understands the following
formatting codes:
@L - left align text
@C - center text
@R - right align text
If you do not use any formatting codes, the default
behavior will be to left align the text. You can use all
Page 4 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
three of these formatting codes within a format string.
This allows you to have some text left aligned, some
centered, and some right aligned. The scope of any
formatting code extends only up until the end of the
string or the next formatting code. So, in something like
"@C#R@Ltitle@Rauthor", you get a header or footer that
looks something like this:
title I author
Paginate also recognizes formatting codes which consist
of an at sign (@), an optional minus sign (-), and a
lowercase hexadecimal digit. These are used for placing
text at specific positions in headers and footers. They
work by adding to or substracting from the current
position. For example, "@R@-a" will begin text ten places
to the left of the right margin. "@C@0" will begin a
piece of text right at the center. They may also be used
more than once together. For example, "@L@9@f" will begin
text at position 25, because "@L" sets the position to 1,
"@9" adds nine to that, and "@f" adds fifteen more.
Please note that "@C@0text" will not work the same as
"@Ctext". Both "@C" and "@R" work by determing the length
of the text segment that follows, and they use that
length to determine a cursor position to begin the text
at. When another formatting code immediately follows "@C"
or "@R", Paginate calculates a position for a string
whose length is zero. Thus, "@C@0text" begins the word
"text" at the center, whereas "@Ctext" centers the word
"text".
EXAMPLES
> Paginate <infile >outfile -F "" -H "@RPage ###d"
This turns off all footers, and it puts on each page a header
that includes the page number on the right side. The right
aligned text for the header on the first page looks like
this: "Page #1".
> Paginate <infile >outfile -f0 "" -f1 "" -hf "" -H
"Title@RPage#d"
This turns off the footer for odd and even pages, but not for
the first page. It sets a default value for the header, and
it turns the header off for the first page. So, it puts the
page number in a footer on the first page, and it puts the
page number in a header on all subsequent pages. Each header
has the word "Title" left aligned and the page number right
Page 5 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
aligned.
> Paginate <infile >outfile -l 1 -F "" -H "Page #R" -h0
"@RPage #R"
This sets the left margin to 1, turns off the footer, and
prints alternate headers on odd and even pages. On odd pages,
it left aligns the page number, and on even pages, it right
aligns the page number.
> Paginate <infile >outfile -T -F "" -ff "@CPage #r" -h0
"Page #r" -h1 "@RPage #r"
This creates a title page, on which there are no headers or
footers. It counts the second page as page #1, and it centers
the page number in a footer for that page. It puts the page
number in a header on all subsequent pages. It left aligns
the page number on even pages and right aligns it on odd
pages. It prints the page number in lowercase roman numerals.
> Paginate <Paginate.man >P.man -F "Page #d@R%a %d %b
%Y" -H "Paginate V1.00@CUser Manual@RPaginate V1.00"
These are the parameters I chose to paginate this manual
with. Just take a look at the headers and footers in this
manual to see the results.
> Type *.h | Paginate >headers -N "%3d " -H "Header
Files@RPage #d" -F "" -l 5 -r 70
This example shows how you can use Paginate on multiple
files. By typing a bunch of files to standard output with
'type', you can use a pipe to redirect the output to
Paginate. It puts a header on each page, and it numbers each
line. It aligns the header with the text rather than with the
line numbers. (Changing the 5 after '-l' to a 1 would align
the header with the line numbers.)
DETAILS
Paginate gets the time only once. This means that it will not
print different times on different pages.
Paginate does not begin page numbering with the title page.
So, if you include a title page, and you want page numbering
to start on page number 1, the first page number should be
set to 1 rather than to 0. This convention is different from
what I have seen on ProWrite.
Paginate puts a formfeed at the end of each page.
Page 6 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
Whenever Paginate finds a formfeed in your input file, it
recognizes that it has come to the end of a page. If it is
supposed to put a footer on that page, it inserts linefeeds
until it reaches the bottom of the page, inserts the footer,
and then inserts a formfeed. If it isn't supposed to put a
footer on that page, it just inserts a formfeed and goes on
to the next page.
Paginate puts the header on the line indicated by "-t", and
it puts the footer on the line indicated by "-b". When a page
doesn't expect a header or footer, Paginate puts a line of
text where the header or footer would go. Thus, a page with a
header and footer on it has fewer lines of text than the same
page without the header and footer.
Paginate always separates each header and footer from the
text by a blank line.
The length of any format string should at no time, which
means after conversions as well as initially, be longer than
the value set by "-r", which is 65 by default.
Rather than specifying the value of the right margin, "-r"
specifies how far the right margin is from the left margin.
This is because Paginate never used the right margin for
anything but finding the difference between the left and
right margins.
This gives you the added advantage of being able to play with
the left margin value without regularly changing the right
margin value to keep the difference the same.
The leftmost left margin is 1, not 0.
The topmost top line is 1, not 0.
All the conversion specifiers and formatting codes are case
sensitive. For example, "@C" instructs Paginate to center
some text, whereas "@c" instructs Paginate to place text 12
spaces to the right of its current position in a header or
footer.
COMPILING
Paginate is written completely in ANSI C. Although I wrote it
on the Amiga, it does not use any Amiga specific features.
You should be able to compile it on any machine with an ANSI
C compiler.
Please note that the Amiga version of GCC 2.3.3 has a bug
which causes this program to go into an infinite loop. I
Page 7 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
don't know if other versions of GCC have this same problem.
HISTORY
I first needed a pagination program when I began writing my
essays with dme instead of with my word processor. I
preferred dme because it was faster and much more
customizable, but it didn't have all the nice features that
my word processor had, including pagination.
My first pagination program was an ARexx script called
Paginate.dme. This would put some lines at the beginning of a
page, and it would center the line number at the bottom of
the page. It would let me control such parameters as first
page number and number of lines per page.
When I began writing XDMD, the soon to be released successor
of DMD, I decided that I wanted something better. I
downloaded Pager to see if it would suit my needs, and it
didn't. So I wrote this program, which is much more powerful
than both Paginate.dme and Pager. In my opinion, it
completely replaces both.
I originally started writing it in C++, since I want to learn
that language. But I found that GCC has a bug in strftime().
So I converted it to C and used DICE.
DISTRIBUTION
You may freely distribute this program by any non-commercial
means as long as the source code, this manual, and the
program are all included together, and no one but myself has
made any changes.
It is OK to recompile the source code with another C compiler
and to redistribute it with the new executable, the source
code, and this manual. You might do this, for example, to
distribute it on machines other than the Amiga. If you do so,
place a note about what you did in a separate text file.
This program may not be distributed with any commercial
product without my written permission.
This program may not be sold by anyone. But it may be
included on disks of freely distributable software which sell
for no more than what Fred Fish charges for his disks, and
which contain as much freely distributable software as they
can hold.
Fred Fish and DevWare are permitted to include this program
on their disks of freely distributable software.
Page 8 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
DISCLAIMER
You use this product at your own risk. I, Fergus Duniho,
offer no guarantees that it will suit any of your purposes. I
do not guarantee the behavior of this program in any way, and
I cannot be held accountable for any misfortunes that result
from the use of this program.
SHAREWARE/FREEWARE
This program is shareware for some people and freeware for
others.
For those who write freeware or public domain software for
the Amiga, this is freeware, for they contribute their
efforts to a pool that we become richer by drawing from.
For sysops, this is freeware, for they volunteer their time
and services to make computing all that much richer.
For students and other poor people, this is freeware, since
they can't afford to pay shareware fees for all the shareware
they might use.
For people who don't live in Canada or the United States,
this is freeware, because I don't want to go through the
bother of cashing checks from foreign banks or exchanging
foreign money. But I live close enough to Canada that
Canadian money isn't a problem.
For crooks, pirates, and other immoral people, this is
freeware, since they wouldn't pay the shareware fee anyway.
For authors of shareware, who do not also write freeware or
public domain software, this is shareware, for they ask
people to pay for their programs, and so I ask the same of
them.
For well-to-do professionals, who do not make unpaid
contributions to the computing community with programs or
services, this is shareware.
For Objectivists, this is shareware, for a good Objectivist
would pay the shareware fee.
For individuals, the shareware fee is $10.00 in American
money or $15.00 in Canadian.
For institutions, churches, and mainframes, the shareware fee
is $20.00 in American money or $30.00 in Canadian.
For the military, the shareware fee is $500.00 in American
Page 9 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
money or $750.00 in Canadian, since the military wouldn't pay
the shareware fee unless it were exorbitantly high.
You will get nothing in return for your shareware fee except
a clean conscience and the knowledge that you have made me
happy by showing your appreciation for my work.
ETHICAL USE
You may not use Paginate for any unethical purpose unless you
pay ten times the shareware fee with clean, honestly earned
money. Stolen or extorted money will not do. Unethical uses
include the pagination of the following sorts of documents:
Propaganda Leaflets for
Religious Cults
Hate Groups
Racial Pride Groups
Communism
Fascism
Nazism
Socialism
Nationalism
Advertisements
Annoying letters asking for money
Chain letters
Smut that degrades women
Death threats
Ransom notes
Besides these, there may be unethical uses I haven't thought
of.
Ethical uses may include the pagination of love letters,
homework, manuals, programs, newsletters, and other harmless
and inoffensive material.
AUTHOR
The one, the only, the incomparable and humble Fergus Duniho.
You may reach me at the following email address:
Internet: fdnh@troi.cc.rochester.edu
If you live in the Rochester calling area, you may also send
me email on FileWorks, the best Amiga BBS in the area.
Page 10 Tue 27 Apr 1993
Paginate V1.00 User Manual Paginate V1.00
You can send all shareware fees to me at
Fergus Duniho
1095 Genesee St.
Rochester, NY 14611
Look for these other fine Amiga software products by me:
The Duniho and Duniho Life Pattern Indicator (DDLI)
XDME Macros by Duniho (XDMD)
AlphaSpell - A command line spelling checker
And if you don't use an Amiga, look for the IBM version of
the DDLI. It's available from the SimTel Software Repository.
Page 11 Tue 27 Apr 1993
